\begin{chapter}{2APL Eclipse Plug-in Editor} \label{chap:eclipse}

The 2APL editor is an Eclipse Xtext based plugin that supports the
editing of 2APL multi-agent programs. In this section we will
describe how to install, configure and use this editor.

\begin{section}{Requirements}
A basic understanding of the 2APL platform, as described in previous
section, is required. In order to run the 2APL editor the latest
version of Eclipse Xtext is required.
\end{section}

\begin{section}{Getting Software and Installation}
One can download the {\tt 2APL Full Package} that contains the 2APL
platform, the Eclipse plug\-in editor, and the Eclipse Xtext version
all configured and installed (286 MB), or alternatively download all
the packages separately and configure them by hand.

In order to use the total package:
\begin{enumerate}

    \item Download the full package from the 2APL homepage using the
    following URL:
    \begin{center}
    {\tt http://apapl.sourceforge.net/}
    \end{center}
    and follow the {\tt Downloads} option.

    \item Extract the files into a directory. In the following, we assume that this directory is named \texttt{D:$\backslash$2APL}

    \item Run the \texttt{2APL Eclipse Editor} shortcut located in the
    directory and select the workspace in the same directory (i.e.,
    \texttt{D:$\backslash$2APL$\backslash$workspace}) as illustrated in
    Figure~\ref{fig:workspace}.
        \begin{figure}[ht]
            \begin{center}
                \epsfig{figure=images/workspace.eps,width=.6\textwidth}
            \end{center}
            \caption{Selecting the workspace for 2APL.}\label{fig:workspace}
        \end{figure}
\end{enumerate}

To manually install the 2APL editor the next procedure should be
followed:

\begin{enumerate}
   \item Download the Eclipse Xtext Galileo 0.7.2 version from its homepage using the following URL:
    \begin{center}
        {\tt http://www.eclipse.org/Xtext/download/}
    \end{center}
    Note that the new versions of Xtext may not work and that
    version 0.7.2 must be downloaded from the
    repository of older versions that is available from the same link.

    \item Extract the contents of the file into a directory. In the sequel, we assume that this directory is named {\tt eclipse}.

    \item Download the Eclipse plug\-in files from the 2APL website using the following URL:
    \begin{center}
    {\tt http://apapl.sourceforge.net/wordpress}
    \end{center}
    and follow the {\tt Downloads} option and select {\tt 2APL Eclipse Plug-in Editor}.

    \item Extract the files to the Eclipse plug\-in directory named {\tt eclipse$\backslash$plugins}.

    \item Download an XML plug\-in for Eclipse using the following URL:
    \begin{center}
    {\tt http://sourceforge.net/projects/editorxml/files/Rinzo}
    \end{center}

    \item Extract the files to the Eclipse plug\-in directory named
    {\tt eclipse$\backslash$plugins}.

    \item Run the Eclipse with \texttt{eclipse.exe} and select the workspace in the 2apl directory (i.e.,
    \texttt{D:$\backslash$2APL$\backslash$workspace}) as illustrated in
    Figure~\ref{fig:workspace}.
\end{enumerate}
\end{section}


\begin{section}{Getting Started with the Editor}

A 2APL multi-agent program, which we will call a 2APL project,
consists of one \texttt{.mas} file and one or more \texttt{.2apl}
files. After starting the Eclipse editor the user can 1) create a
new 2APL project based on existing multi-agent program files (i.e.,
\texttt{.mas} and \texttt{.2apl} files), 2) create a new 2APL
project from scratch (i.e., without \texttt{.mas} and \texttt{.2apl}
files), and 3) load and edit an existing 2APL project.

\begin{subsection}{Creating and Editing a New 2APL Project based on existing Multi-Agent Program Files}
This option can be used if a multi-agent program already exists. The
multi-agent program is assumed to be developed with another editor.
One can develop the multi-agent program further with the 2APL
Eclipse editor.

\begin{enumerate}
        \item To create a new empty project without any files, select the menu \texttt{File -> new -> Project}.
        In the Wizard window, select \texttt{General -> Project}, press {\tt Next}, give the project
        a name, and press {\tt Finish}. The new empty project will
        appear in the left panel of the Eclipse window.

        \item Select the created project and right click the mouse and choose {\tt Import}.
        Select in the {\tt Select Wizard} the option {\tt General -> File System} and click {\tt
        Next}.

        \item Use {\tt Browse} and select the directory in which the already written multi-agent
        program files are located.

        \item One can now select the files to import and click {\tt
        Finish}. The files are now available in the project in the
        left panel of the editor.
\end{enumerate}

\end{subsection}

\begin{subsection}{Creating and Editing a New 2APL Project from Scratch}

In order to create a new 2APL project from scratch (i.e., without
assuming an existing multi-agent program), we first have to create a
2APL project followed by creating a multi-agent program. The
following steps should be taken.
\begin{enumerate}
        \item Follow the {\tt File -> New -> Project...} of the Eclipse user
        interface. Choose {\tt APAPL project} by following the item {\tt
        Xtext} in the select wizard and press {\tt Next}. These
        steps are illustrated in Figure~\ref{fig:usage1}.
        \begin{figure}[h]
            \begin{minipage}{0.6\linewidth}
                \begin{center}
                    \epsfig{figure=images/usage1.eps,width=.6\textwidth}
                \end{center}
            \end{minipage}
            \hspace{.5cm}
            \begin{minipage}{0.3\linewidth}
                \begin{center}
                    \epsfig{figure=images/usage2.eps,width=\textwidth}
                \end{center}
            \end{minipage}
            \caption{Create a new 2APL project.}\label{fig:usage1}
        \end{figure}

        \item Give the project a name (e.g. \texttt{push-up}), as
        illustrated in Figure~\ref{fig:usage3}(left).

        \item Open the created project by double click the {\tt push-up} item in the left panel of the Eclipse window.
        This opens the {\tt push-up} project consisting of the \texttt{pushup.mas} and {\tt agent.2apl}
        files. These files can be opened and edited by clicking on
        the files {\tt agent.2apl} or {\tt pushup.mas}.
        Figure~\ref{fig:usage3} (right) illustrates the opened file {\tt
        agent} in the 2APL editor which can now be edited.

        \begin{figure}[ht]
            \begin{minipage}{0.3\linewidth}
                \begin{center}
                    \epsfig{figure=images/usage3.eps,width=\textwidth}
                \end{center}
            \end{minipage}
            \hspace{.5cm}
            \begin{minipage}{0.6\linewidth}
            \begin{center}
                \epsfig{figure=images/usage4.eps,width=\textwidth}
            \end{center}
            \end{minipage}
        \caption{Giving a name to a new project (left), and Editing 2APL files (right).}\label{fig:usage3}
        \end{figure}

        \item New agent programs (i.e., {\tt .2apl} files) can be added to this project by
        selecting the {\tt push-up} project, left click mouse, and
        follow {\tt New -> File} menu item. Enter a file name with
        {\tt .2apl} extension. This operation is illustrated in
        Figure~\ref{fig:newfile1}. The new file is now available in the Eclipse project.

            \begin{figure}[h]
                \begin{minipage}{0.6\linewidth}
                    \begin{center}
                        \epsfig{figure=images/newfile1.eps,width=.6\textwidth}
                    \end{center}
                \end{minipage}
                \begin{minipage}{0.4\linewidth}
                    \begin{center}
                        \epsfig{figure=images/newfile2.eps,width=\textwidth}
                    \end{center}
                \end{minipage}
                \caption{Adding new files to a project.}\label{fig:newfile1}
            \end{figure}

\end{enumerate}

\begin{subsection}{Editing Existing 2APL Projects}
Existing 2APL projects, e.g., the multi-agent program {\tt harry and
sally} in the {\tt 2APL$\backslash$examples$\backslash$harry and
sally}\footnote{For unix systems, path representations should be
modified accordingly.}, can be loaded and edited using the import
wizard. For importing an existing project, the existing projects
should be located in the directory
\texttt{D:$\backslash$2APL$\backslash$workspace}. Once the projects
are located in this directory, one can choose {\tt File -> import}.
A selection window will appear. Select item {\tt General -> Existing
Projects into Workspace}, press {\tt Next}, browse from directory
containing the project files, and press {\tt Finish}. The project
will appear in the right panel. These steps are illustrated in
Figure~\ref{fig:existingproject}.
    \begin{figure}[h]
            \begin{center}
                \epsfig{figure=images/existingprojects.eps,width=\textwidth}
            \end{center}
        \begin{minipage}{0.5\linewidth}
            \begin{center}
                \epsfig{figure=images/existingproject1.eps,width=\textwidth}
            \end{center}
        \end{minipage}
        \hspace{.5cm}
        \begin{minipage}{0.5\linewidth}
            \begin{center}
                \epsfig{figure=images/existingproject2.eps,width=\textwidth}
            \end{center}
        \end{minipage}
        \caption{Editing existing project.}\label{fig:existingproject}
    \end{figure}
\end{subsection}

\end{subsection}

\end{section}


\begin{section}{Syntax coloring}

To change to colors in the 2APL editor go to the
\texttt{Preferences} page, under the menu \texttt{Window}, and then
select \texttt{Xtext Languages}, \texttt{APAPL}, \texttt{Syntax
Coloring}. Here one can change the colors for some rules. One can
also restore the color settings, back to black as default, by
clicking the \texttt{Restore Defaults} button. This is illustrated
in Figure~\ref{fig:coloring}.

        \begin{figure}[ht]
            \begin{center}
                \epsfig{figure=images/color1.eps,width=.5\textwidth}
            \end{center}\label{fig:color1}
            \caption{Modifying the color of 2APL syntax in the editor.}\label{fig:coloring}
        \end{figure}

\end{section}


\begin{section}{Run the project from Eclipse}
    To run the 2APL platform from Eclipse follow the next steps.
    \begin{enumerate}
    \item Open the \texttt{External Tools Configurations} as
    illustrated in Figure~\ref{fig:runconfiguration}.
        \begin{figure}[ht]
            \begin{center}
                \epsfig{figure=images/runconfiguration.eps,width=.5\textwidth}
            \end{center}
            \caption{The first step to run 2APL from Eclipse.}\label{fig:runconfiguration}
        \end{figure}

    \item In the External Tools Configurations window, right click \texttt{program} and select
    \texttt{new}. This is illustrated in the Figure~\ref{fig:runconfiguration1}.
        \begin{figure}[ht]
            \begin{center}
                \epsfig{figure=images/runconfiguration1.eps,width=.3\textwidth}
            \end{center}
            \caption{The second step to run 2APL from Eclipse.}\label{fig:runconfiguration1}
        \end{figure}

    \item In the configurations window, set the following values.
        \begin{enumerate}
        \item Name: a name for the run configuration (e.g. \texttt{2APL with GUI})

        \item Location: the full path to the java.exe\\
        (e.g. \texttt{C:$\backslash$Program
        Files$\backslash$Java$\backslash$jdk1.6.0\_04$\backslash$bin$\backslash$java.exe}).

        \item Working Directory: the path to the 2APL directory where {\tt 2apl.jar} is
        located\\
        (e.g. \texttt{D:$\backslash$apapl}).

        \item Arguments: \texttt{-jar 2apl.jar -nojade "\$\{project\_loc\}"}
        \end{enumerate}

        These steps are illustrated in Figure~\ref{fig:platform}.
        Note that the required paths are correctly entered. It is also important to note that
        the behavior of the run configuration can be modified by changing the
        Arguments. Add the option \texttt{-nogui} after \texttt{-nojade} to
        disable the 2APL GUI. Or leave the \texttt{-nojade} option out of the
        Arguments to get a choice to enable the jade platform.
        \begin{figure}[ht]
                \begin{center}
                    \epsfig{figure=images/platform.eps,width=.6\textwidth}
                \end{center}
                \caption{Creating a direct 2APL Run item in Eclipse.}\label{fig:platform}
            \end{figure}

    \item Select the multi-agent system file with the \texttt{.mas} extension to run.
    Choose the run configuration that is just created as illustrated in
    Figure~\ref{fig:run}. The 2APL platform will start running the selected multi-agent program.
        \begin{figure}[ht]
            \begin{center}
                \epsfig{figure=images/run.eps,width=.5\textwidth}
            \end{center}
            \caption{Running 2APL from Eclipse.}\label{fig:run}
        \end{figure}

    \end{enumerate}
\end{section}
\end{chapter}
